Mule has an internal notification mechanism which can be used to tap into server notification such as a Component being added, the Model being initialised or the Manager being started. These notifications can be useful to allow custom components such as Agents or Mule managed components to react to change in the server.

Don't confuse these notifications with service events that mule manages between your components and external applications. These Server Notifications provide notifications between objects that comprise the Mule Server, where as service events are the business operations that your business services process.

 
There are currently 10 types of Server Notifications -
 

1. Manager Notification - is fired when state changes on the Mule mananger such as initialising, sarting and stopping.
2. Model Notification - is fired when state changes on the Mule Model such as initialising, sarting and stopping or components being registered or unregistered.
3. Component Notification - is fire when a particular component is started, stopped, paused, resumed.
4. Management Notification - is fired when monitored resources are low (not yet implemented)
5. Custom Notification - can be fired by objects themselves to custom notification listeners, and can be used to customise notifications on Agents, Components, connectors etc.
6. Admin Notification - is fired when requests are received by the Mule Admin agent. These are usually trigged by MuleClient calls using the RemoteDispatcher, which proxies calls to a remote server.
7. Connection Notification - happen when a connector attempts to connect to its underlying resource. Notifications are fired when a connection is made, released or the connection attempt fails.
8. Message Notification - These notifications are fire when an event is sent or received in the system. These are very good for tracing, but are not enabled by default as there is a performance impact when using these. Read below to find out how to enable them.
9. Security Notification - is fired when a request is denied security access.
10. Space Monitor Notification - is fired from space implementations such as JavaSpaces, JCache or the Mule internal space implementaiton when events are fired into or out of a space. See [Spaces] for more information.

To become a server event listener objects can implement one of the following interfaces-

1. org.mule.impl.internal.notifications.ManagerNotificationListener
2. org.mule.impl.internal.notifications.ModelNotificationListener
3. org.mule.impl.internal.notifications.ComponentNotificationListener
4. org.mule.impl.internal.notifications.ManagementNotificationListener
5. org.mule.impl.internal.notifications.CustomNotificationListener
6. org.mule.impl.internal.notifications.AdminNotificationListener
7. org.mule.impl.internal.notifications.ConnectionNotificationListener
8. org.mule.impl.internal.notifications.MessageNotificationListener
9. org.mule.impl.internal.notifications.SecurityNotificationListener
10. org.mule.impl.internal.notifications.SpaceMonitorNotificationListener

these all have a single method -

public void onNotification(UMOServerNotification notification);

Depending on the listener implemented only certain events will be received, for example the object implements ManagerNotificationListener only events of type ManagerNotification will be received. Objects can implement more than one listener to receive more types of event.

Listeners can be registered on the UMOManager -

MuleManager.getInstance().registerListener(listener);

Each event has an action code that determines the type of event. The action code can be queried in the onEvent method to determine its type. To have an object do something when the Model initialises -

public class MyObject implements ModelNotificationListener
{
    public MyObject()
    {
        MuleManager.getInstance().registerListener(this);
    }

    public void onNotification(UMOServerNotification notification)
    {
        if (notification.getAction() == ModelNotification.MODEL_INITIALISED)
        {
            system.out.println("The Model is initialised!");
        }
    }
}

Enabling MessageNotifications

Message Notifications are very useful as they provide a snapshot of all information sent into and out of the the Mule Server. These notifications are fired when ver a message is received or sent. As you can imagine, these additional events will have some impact on performance so they are turned off by default. To enable these events you need to set the enableMessageEvents to true on the <mule-environment-properties> i.e.

<mule-environment-properties enableMessageEvents="true"/>

Firing custom Notifications

Custom Notifications can be fired by objects in Mule to notify custom listeners. For example a discovery Agent might fire a 'Client Found' event when a client connects.

To fire a custom event use -

CustomNotification n = new CustomNotification("Hello");
MuleManager.getInstance().fireNotification(e);

Any objects implementing CustomNotificationListener will receive this event. It's a good idea to extend the CustomNotification and define actions for your custom event type. To use the Discovery Agent example above -

DiscoveryNotification n = new DiscoveryNotification(client, DiscoveryNotification.CLIENT_ADDED);
MuleManager.getInstance().fireNotification(e);

 

Non-system objects in Mule can only fire Custom notifications through the manager, attempting to fire other events such as ModelNotification will cause an UnsupportedOperationException.

 

Using Event Subscriptions

You can associate a subscription with an event listener so that only events the match the subscription will be passed to the listener. The subscription is a wildcard String expression that will be matched against the 'Resource ID' of the event (see the next section). So to register interest in Component events where the component is called MyService1 you can use -

MuleManager.getInstance().registerListener(listener, "MyService1");

If you wanted to match all components with Service in the name you can use -

MuleManager.getInstance().registerListener(listener, "*Service*");

Notification payloads

All notifications extend java.util.EventObject and the payload of the object can be accessed using the getSource() method. The following table describes the event payloads for each type of event.

Notification Actions

the following describes the actions for each Notification type.

ManagerNotification

ModelNotification

ComponentNotification

ManagementNotification

Not implemented yet

CustomNotification

AdminNotification

ConnectionNotification

MessageNotification

SecurityNotification

SpaceNotificationNotification